3D Graphics Programming with QuickDraw 3D 1.5.4

Managing Renderer Features

QuickDraw 3D provides routines that you can use to manage a renderer's features.

Q3Renderer_HasModalConfigure

You can use the Q3Renderer_HasModalConfigure function to determine whether a renderer can display a modal settings dialog box.



 
TQ3Boolean Q3Renderer_HasModalConfigure (TQ3RendererObject renderer);

renderer: A renderer.

DESCRIPTION

The Q3Renderer_HasModalConfigure function returns, as its function result, a Boolean value that indicates whether the renderer specified by the renderer parameter can display a modal settings dialog box (kQ3True ) or not (kQ3False ).

Q3Renderer_ModalConfigure

You can use the Q3Renderer_ModalConfigure function to pop up a modal dialog box used to configure the renderer's settings.



 
TQ3Status Q3Renderer_ModalConfigure (

                     TQ3RendererObject renderer, 

                     TQ3DialogAnchor dialogAnchor, 

                     TQ3Boolean *canceled);

renderer: A renderer.
dialogAnchor: A dialog anchor data structure (see [link] ).
canceled: Returned value indicating whether the request has been canceled (kQ3True ) or not (kQ3False ).

DESCRIPTION

The Q3Renderer_ModalConfigure function displays a modal settings dialog box to configure the settings for the renderer specified by the renderer parameter. The canceled parameter is a Boolean that returns kQ3True if the request has been canceled, kQ3False otherwise.

The Q3Renderer_ModalConfigure function returns kQ3Failure if an error occurred.

Q3Renderer_GetConfigurationData

An application can use the Q3Renderer_GetConfigurationData function to access private renderer configuration data, which it can then save in a preference file or style template. The application should tag this data with the renderer's object name.



 
TQ3Status Q3Renderer_GetConfigurationData (

                     TQ3RendererObject    renderer,

                     unsigned char        *dataBuffer,

                     unsigned long        bufferSize,

                     unsigned long         *actualDataSize);

renderer: A renderer object.
dataBuffer: A pointer to a data buffer.
bufferSize: The actual size in bytes of the memory block pointed to by dataBuffer .
actualDataSize: On return, the actual number of bytes written to the buffer. If you set dataBuffer to null , actualDataSize returns the number of bytes that will be required to store the configuration data .

DESCRIPTION

The Q3Renderer_GetConfigurationData function stores private configuration data for the renderer object designated by renderer in a buffer pointed to by the dataBuffer parameter, and returns in actualDataSize the number of bytes written. If you set dataBuffer to null , Q3Renderer_GetConfigurationData will return in actualDataSize the buffer size required, without writing data out.

Q3Renderer_SetConfigurationData

You can use the Q3Renderer_SetConfigurationData function to set a renderer to a configuration state previously accessed by Q3Renderer_GetConfigurationData.



 
TQ3Status Q3Renderer_SetConfigurationData (

                     TQ3RendererObject    renderer,

                     unsigned char        *dataBuffer,

                     unsigned long         bufferSize);

renderer: A renderer object.
dataBuffer: A pointer to a data buffer.
bufferSize: The actual size in bytes of the memory block pointed to by dataBuffer .

DESCRIPTION

The Q3Renderer_SetConfigurationData function sets the renderer designated by renderer to the configuration state determined by the private data structure pointed to by dataBuffer. The bufferSize parameter indicates the size of the buffer.

Q3RendererClass_GetNickNameString

You can use the Q3RendererClass_GetNickNameString function to to get a renderer's name string. The name string can then be used to provide user selections, for example in a menu.



 
TQ3Status Q3RendererClass_GetNickNameString(

                     TQ3ObjectType               rendererClassType,

                     TQ3ObjectClassNameString    rendererClassString);

rendererClassType: A renderer object type.
rendererClassString: A string containing the renderer's name.

DESCRIPTION

The Q3RendererClass_GetNickNameString function returns, in the rendererClassString parameter, the user-identifiable name of a renderer.

The renderer is responsible for storing the name in a localizable format--for example as a resource. If Q3RendererClass_GetNickNameString returns NULL in rendererClassString, then the caller may choose to use the renderer's class name instead. Applications should always try to get the name string before using the class name, because the class name is not localizable.